home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / etc / RCS / Fmt.man,v < prev    next >
Text File  |  1990-05-07  |  11KB  |  354 lines
  1. head     1.3;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.3
  10. date     90.05.07.11.58.35;  author jhh;  state Exp;
  11. branches ;
  12. next     1.2;
  13.  
  14. 1.2
  15. date     89.06.19.14.16.57;  author jhh;  state Exp;
  16. branches ;
  17. next     1.1;
  18.  
  19. 1.1
  20. date     89.06.05.12.35.01;  author jhh;  state Exp;
  21. branches ;
  22. next     ;
  23.  
  24.  
  25. desc
  26. @@
  27.  
  28.  
  29. 1.3
  30. log
  31. @added mention of FMT_MY_FORMAT constant
  32. @
  33. text
  34. @'\" Copyright 1989 Regents of the University of California
  35. '\" Permission to use, copy, modify, and distribute this
  36. '\" documentation for any purpose and without fee is hereby
  37. '\" granted, provided that this notice appears in all copies.
  38. '\" The University of California makes no representations about
  39. '\" the suitability of this material for any purpose.  It is
  40. '\" provided "as is" without express or implied warranty.
  41. '\" 
  42. '\" $Header: /sprite/src/lib/c/etc/RCS/Fmt.man,v 1.2 89/06/19 14:16:57 jhh Exp Locker: jhh $ SPRITE (Berkeley)
  43. '/" 
  44. .so \*(]ltmac.sprite
  45. .HS Fmt lib
  46. .BS
  47. '\" Note:  do not modify the .SH NAME line immediately below!
  48. .SH NAME
  49. Fmt_Convert \- Package for converting data from one byte-order/alignment
  50. format to another. 
  51. .SH SYNOPSIS
  52. .nf
  53. \fB#include <fmt.h>\fR
  54. .sp
  55. int
  56. .br
  57. \fBFmt_Convert\fR(\fIcontents, inFormat, inSizePtr, inBuffer, outFormat, outSizePtr, outBuffer\fP)
  58. .sp
  59. int
  60. .br
  61. \fBFmt_Size\fR(\fIcontents, inFormat, inSizePtr, outFormat, outSizePtr\fR)
  62. .SH ARGUMENTS
  63. .AS Fmt_Format outSizePtr
  64. .AP char *contents in
  65. String describing contents of \fIinBuffer\fR (see below).
  66. .AP Fmt_Format inFormat in
  67. Byte-order/alignment format of data in \fIinBuffer\fR.
  68. .AP int *inSizePtr in/out
  69. Points to size of \fIinBuffer\fR.  Upon return \fI*inSizePtr\fR is
  70. the number of
  71. bytes actually used.
  72. .AP char *inBuffer in
  73. Data to be converted.
  74. .AP Fmt_Format outFormat in
  75. Byte-order/alignment format of data in \fIoutBuffer\fR.
  76. .AP int *outSizePtr in/out
  77. Points to size of \fIoutBuffer\fR.  Upon return \fI*outSizePtr\fR contains 
  78. the number of
  79. bytes actually used. For \fBFmt_Size\fR this is strictly an out parameter.
  80. .AP char *outBuffer in
  81. Converted data.
  82. .BE
  83.  
  84. .SH DESCRIPTION
  85. .PP
  86. \fBFmt_Convert\fR converts data between different 
  87. byte-order/alignment formats. Typically this is done between different
  88. machine types, but it can be used to convert between two compilers that
  89. align data differently.
  90. \fIInFormat\fR specifies the byte-order/alignment format of the 
  91. data in \fIinBuffer\fR,
  92. and \fIoutFormat\fR specifies the byte-order/alignment format of the data 
  93. in \fIoutBuffer\fR after the conversion.
  94. The data to be converted is read from \fIinBuffer\fR and the converted data is
  95. written to \fIoutBuffer\fR.
  96. The parameter \fIinSizePtr\fR points to the size of the input buffer. 
  97. When \fBFmt_Convert\fR returns
  98. \fI*inSizePtr\fR contains the number of bytes that were actually used.
  99. It is possible for less than the entire buffer to be converted depending
  100. upon the \fIcontents\fR string. 
  101. See below for more details on \fIcontents\fR.
  102. The parameter \fIoutSizePtr\fR points to the size of the output buffer. 
  103. When \fBFmt_Convert\fR returns \fI*outSizePtr\fR contains the
  104. number of bytes actually used. 
  105. .PP
  106. \fBFmt_Size\fR computes the minimum size output buffer needed converting
  107. the data at described by the \fIcontents\fR string
  108. The result is returned in \fI*outSizePtr\fR.
  109. This size can then be passed to \fBFmt_Convert\fR (assuming that the format
  110. and contents parameters remain the same).
  111.  
  112. The legal values for the format parameters are defined in fmt.h.
  113. They are as follows:
  114. .IP "\fBFMT_68K_FORMAT\fR"
  115. The byte-order/alignment format of code compiled by Gcc for 
  116. Motorola 680x0 machines.
  117. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  118. the most significant byte.  
  119. Halfwords, words and doublewords are aligned on even 
  120. boundaries.  
  121. The alignment of structures and unions equals the most restrictive alignment
  122. of one of their members, such that they are at least aligned on 
  123. an even
  124. boundary.
  125. The size of structures and unions is a multiple of their alignment.
  126. .IP "\fBFMT_VAX_FORMAT\fR"
  127. The byte-order/alignment format of the Vax.
  128. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  129. the least significant byte.  
  130. Halfwords are aligned on even boundaries. 
  131. Words and doublewords are aligned on word 
  132. boundaries.  
  133. The alignment of structures and unions equals the most restrictive alignment
  134. of one of their members.
  135. The size of structures and unions is a multiple of their alignment.
  136. .IP "\fBFMT_SPUR_FORMAT\fR"
  137. The byte-order/alignment format of code compiled by Gcc for the Spur.
  138. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  139. the least significant byte.
  140. Halfwords are aligned on even boundaries, words are aligned on quad boundaries,
  141. and doublewords are aligned on oct boundaries.
  142. The alignment of structures and unions equals the most restrictive alignment
  143. of one of their members, such that they are at least aligned on 
  144. a quad
  145. boundary.
  146. The size of structures and unions is a multiple of their alignment.
  147. .IP "\fBFMT_SPARC_FORMAT\fR"
  148. The byte-order/alignment format of code compiled by the SunOS compiler
  149. for the Sparc architecture.
  150. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  151. the 
  152. most
  153. significant byte.
  154. Halfwords are aligned on even boundaries, words are aligned on quad boundaries,
  155. and doublewords are aligned on oct boundaries.
  156. The alignment of structures and unions equals the most restrictive alignment
  157. of one of their members.
  158. The size of structures and unions is a multiple of their alignment.
  159. .IP "\fBFMT_MIPS_FORMAT\fR"
  160. The byte-order/alignment format of code compiled by the Ultrix compiler
  161. for the Mips (DecStation3100) architecture.
  162. Treating an integer as an array of 4 bytes (char buf[4]), buf[0] contains
  163. the 
  164. least
  165. significant byte.
  166. Halfwords are aligned on even boundaries, words are aligned on quad boundaries,
  167. and doublewords are aligned on oct boundaries.
  168. The alignment of structures and unions equals the most restrictive alignment
  169. of one of their members.
  170. The size of structures and unions is a multiple of their alignment.
  171. .VS
  172. .IP "\fBFMT_MY_FORMAT\fR"
  173. This format is set to the
  174. format of the machine on which the code is running.
  175. This relieves the program that is using the \fBFmt\fR package
  176. from having to
  177. decide with format is appropriate for a particular machine.
  178. .VE
  179. .PP
  180. The \fIcontents\fR parameter is used to describe the data types that comprise
  181. the input buffer. The buffer can contain bytes, halfwords (2 bytes),
  182. words (4 bytes), doublewords (8 bytes), structures, and unions.
  183. These data types are represented in the contents string using the 
  184. following characters.
  185. .IP \fBb\fR
  186. One byte.
  187. .IP \fBh\fR
  188. One halfword (2 bytes).
  189. .IP \fBw\fR
  190. One word (4 bytes).
  191. .IP \fBd\fR
  192. One double word (8 bytes).
  193. .IP \fB{\fR
  194. The start of a structure.
  195. .IP \fB}\fR
  196. The end of a structure.
  197. .IP \fB(\fR
  198. The start of a union. The '\fB(\fR' must be followed by a discriminant that 
  199. indicates which of the components of the union is to be converted.
  200. The discriminant is a decimal number that gives the index of the component,
  201. starting at 0.
  202. .IP \fB)\fR
  203. The end of a union.
  204. .IP \fB0\fR-\fB9\fR*
  205. A decimal number following a data type (byte, halfword, word, doubleword,
  206. structure, or union) indicates that the data type is repeated the
  207. given number of times. For instance, the string "w5" means that the 
  208. input contains 5 consecutive words. There is an ambiguity that arises
  209. when describing the contents of a union. "w5" can either refer to one
  210. component of 5 words, or to 5 components of one word each. 
  211. The abiguity is resolved by having "w5" refer to one component of 5 words,
  212. and "wwwww" refer to 5 components of one word. 
  213. Similarly, "w*" refers to one component (see next paragraph for description
  214. of the '*' character).
  215. .IP \fB*\fR
  216. A '\fB*\fR' means 1 or more repetitions of the previous data type. The number of
  217. repetitions is determined by the amount of data remaining in the input
  218. buffer. Care must be taken if the '\fB*\fR' character is anything but the
  219. last character in the string. Certain formats place constraints on the
  220. sizes of unions and structures that may cause the '\fB*\fR' character to
  221. give unwanted results. For example, consider a structure
  222. consisting of a word followed by a byte that is defined as "{wb*}".
  223. In the Spur format "b*" will refer to 4 bytes, while in the 68K format
  224. it will refer to 2 bytes.
  225.  
  226. .PP
  227. The following are examples of input data types and content strings.
  228. .sp
  229. \fIData\fR:
  230. .sp
  231.     int    foo[5];
  232. .sp
  233. \fIContent string\fR:
  234. .sp
  235.     "w5" or "w*" or "wwwww" 
  236. .sp
  237. \fIData\fR:
  238. .sp
  239. .DS
  240. .ta 1c 2c 4c 5c 6c
  241.     struct    flea    {
  242.         char        mite;
  243.         int        spider;
  244.         int        worm;
  245.         short        moth;
  246.         short        mosquito;
  247.         short        beetle;
  248.         int        fly[5];
  249.         char        gnat[50];
  250.     };
  251. .DE
  252. .sp
  253. \fIContent string\fR:
  254. .sp
  255. "{bwwh3w5b*}" 
  256. .sp
  257. \fIData\fR:
  258. .sp
  259. .DS
  260. .ta 1c 2c 5c 7c 9c
  261.     struct  foo    {
  262.         char    bar;
  263.         int    baz;
  264.         union {
  265.             short    quux;
  266.             double     cow;
  267.         } dog[6];
  268.     };
  269. .DE
  270. .sp
  271. \fIContent string\fR:
  272. .sp
  273.     "{bw(0hd)6}" or "{bw(0hd)*}"  if "quux" is the component of "dog" to be 
  274. converted, 
  275. .br
  276. or,
  277. .br
  278.     "{bw(1hd)6}" or "{bw(1hd)*}" if "cow" is the component of "dog" to be
  279. converted.
  280.  
  281. .SH "RETURN VALUES"
  282. .PP
  283. The following return codes are defined in fmt.h:
  284. .IP "\fBFMT_OK\fR (0)"
  285. Procedure completed properly
  286. .IP "\fBFMT_CONTENT_ERROR\fR"
  287. The \fIcontents\fR parameter contained an error.
  288. .IP "\fBFMT_INPUT_TOO_SMALL\fR"
  289. The input buffer was smaller than indicated by \fIcontents\fR.
  290. .IP "\fBFMT_OUTPUT_TOO_SMALL\fR"
  291. The output buffer was too small to hold the converted data. This is only
  292. returned by \fBFmt_Convert\fR.
  293. .IP "\fBFMT_ILLEGAL_FORMAT\fR"
  294. One of the format parameters was illegal.
  295. .SH KEYWORDS
  296. byte-order, byte-swap, alignment, data conversion
  297.  
  298. @
  299.  
  300.  
  301. 1.2
  302. log
  303. @added mips format
  304. @
  305. text
  306. @d9 1
  307. a9 1
  308. '\" $Header: /sprite/src/lib/c/etc/RCS/Fmt.man,v 1.1 89/06/05 12:35:01 jhh Exp Locker: jhh $ SPRITE (Berkeley)
  309. d138 8
  310. @
  311.  
  312.  
  313. 1.1
  314. log
  315. @Initial revision
  316. @
  317. text
  318. @d9 1
  319. a9 1
  320. '\" $Header: /sprite/lib/forms/RCS/proto.man,v 1.5 89/01/27 08:36:02 ouster Exp $ SPRITE (Berkeley)
  321. d127 11
  322. a137 2
  323. .PP
  324. Not implemented yet.
  325. d157 1
  326. a157 1
  327. The start of a union. The \fB(\fR must be followed by a discriminant that 
  328. d166 1
  329. a166 1
  330. given number of times. For instance, the string \fIw5\fR means that the 
  331. d168 1
  332. a168 1
  333. when describing the contents of a union. \fIw5\fR can either refer to one
  334. d170 4
  335. a173 4
  336. The abiguity is resolved by having \fIw5\fR refer to one component of 5 words,
  337. and \fIwwwww\fR refer to 5 components of one word. 
  338. Similarly, \fIw*\fR refers to one component (see next paragraph for description
  339. of the \fI*\fR character).
  340. d175 1
  341. a175 1
  342. A \fB*\fR means 1 or more repetitions of the previous data type. The number of
  343. d177 1
  344. a177 1
  345. buffer. Care must be taken if the \fB*\fR character is anything but the
  346. d179 1
  347. a179 1
  348. sizes of unions and structures that may cause the \fB*\fR character to
  349. d181 2
  350. a182 2
  351. consisting of a word followed by a byte that is defined as \fI{wb*}\fR.
  352. In the Spur format \fIb*\fR will refer to 4 bytes, while in the 68K format
  353. @
  354.